home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / elispman.lha / elispman / elisp-35 (.txt) < prev    next >
GNU Info File  |  1993-05-11  |  50KB  |  770 lines

  1. This is Info file elisp, produced by Makeinfo-1.52 from the input file
  2. elisp.texi.
  3.    This file documents GNU Emacs Lisp.
  4.    This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
  5. Emacs Version 19.
  6.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  7. Cambridge, MA 02139 USA
  8.    Copyright (C) 1990, 1991, 1992 Free Software Foundation, Inc.
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided that
  14. the entire resulting derived work is distributed under the terms of a
  15. permission notice identical to this one.
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that this permission notice may be stated in a
  19. translation approved by the Foundation.
  20. File: elisp,  Node: Sexp Diary Entries,  Next: Appt Customizing,  Prev: Including Diary Files,  Up: Calendar
  21. Sexp Entries and the Fancy Diary Display
  22. ========================================
  23.                                       Sexp diary entries allow you to
  24. do more than just have complicated conditions under which a diary entry
  25. applies.  If you use the fancy diary display, sexp entries can generate
  26. the text of the entry depending on the date itself.  For example, the
  27. anniversary diary entry described above (*note Special Diary
  28. Entries::.) can insert the number of years since the anniversary date
  29. into the text of the diary entry.  Thus the `%d' in the dairy entry
  30.                                         %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
  31.                                    gets replaced by the age, so on
  32. October 31, 1990 the entry appears in the fancy diary buffer as
  33.                                         Arthur's birthday (42 years old)
  34.                                    If the diary file instead contains
  35. the entry
  36.                                         %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
  37.                                    the entry in the fancy diary buffer
  38. for October 31, 1990 becomes
  39.                                         Arthur's 42nd birthday
  40.                                       Similarly, cyclic diary entries
  41. can interpolate the number of repetitions that have occurred:
  42.                                         %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
  43.                                    causes the diary entry
  44.                                         Renew medication (5th time)
  45.                                    to appear in the fancy diary display
  46. on September 8, 1990.
  47.                                       The generality of sexp diary
  48. entries lets you specify any diary entry that you can describe
  49. algorithmically.  Suppose you get paid on the 21st of the month if it
  50. is a weekday, and to the Friday before if the 21st is on a weekend.
  51. The diary entry
  52.                                         &%%(let ((dayname (calendar-day-of-week date))
  53.                                                  (day (car (cdr date))))
  54.                                               (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
  55.                                                   (and (memq day '(19 20)) (= dayname 5)))
  56.                                                  ) Pay check deposited
  57.                                    applies to just those dates.  This
  58. example illustrates how the sexp can depend on the variable `date';
  59. this variable is a list (MONTH DAY YEAR) that gives the Gregorian date
  60. for which the diary entries are being found.  If the value of the
  61. expression is `t', the entry applies to that date.  If the expression
  62. evaluates to `nil', the entry does *not* apply to that date.
  63.                                       The following sexp diary entries
  64. take advantage of the ability (in the fancy diary display) to concoct
  65. diary entries based on the date:
  66.                                   `%%(diary-sunrise-sunset)'
  67.                                         Make a diary entry for the
  68.                                         local times of today's sunrise
  69.                                         and sunset.
  70.                                   `%%(diary-phases-of-moon)'
  71.                                         Make a diary entry for the
  72.                                         phases (quarters) of the moon.
  73.                                   `%%(diary-day-of-year)'
  74.                                         Make a diary entry with today's
  75.                                         day number in the current year
  76.                                         and the number of days
  77.                                         remaining in the current year.
  78.                                   `%%(diary-iso-date)'
  79.                                         Make a diary entry with today's
  80.                                         equivalent ISO commercial date.
  81.                                   `%%(diary-julian-date)'
  82.                                         Make a diary entry with today's
  83.                                         equivalent date on the Julian
  84.                                         calendar.
  85.                                   `%%(diary-astro-day-number)'
  86.                                         Make a diary entry with today's
  87.                                         equivalent astronomical
  88.                                         (Julian) day number.
  89.                                   `%%(diary-hebrew-date)'
  90.                                         Make a diary entry with today's
  91.                                         equivalent date on the Hebrew
  92.                                         calendar.
  93.                                   `%%(diary-islamic-date)'
  94.                                         Make a diary entry with today's
  95.                                         equivalent date on the Islamic
  96.                                         calendar.
  97.                                   `%%(diary-french-date)'
  98.                                         Make a diary entry with today's
  99.                                         equivalent date on the French
  100.                                         Revolutionary calendar.
  101.                                   `%%(diary-mayan-date)'
  102.                                         Make a diary entry with today's
  103.                                         equivalent date on the Mayan
  104.                                         calendar.
  105.                                    Thus including the diary entry
  106.                                         &%%(diary-hebrew-date)
  107.                                    causes every day's diary display to
  108. contain the equivalent date on the Hebrew calendar, if you are using
  109. the fancy diary display.  (With simple diary display, the line
  110. `&%%(diary-hebrew-date)' appears in the diary for any date, but does
  111. nothing particularly useful.)
  112.                                       There are a number of other
  113. available sexp diary entries that are important to those who follow the
  114. Hebrew calendar:
  115.                                   `%%(diary-rosh-hodesh)'
  116.                                         Make a diary entry that tells
  117.                                         the occurrence and ritual
  118.                                         announcement of each new Hebrew
  119.                                         month.
  120.                                   `%%(diary-parasha)'
  121.                                         Make a Saturday diary entry
  122.                                         that tells the weekly synagogue
  123.                                         scripture reading.
  124.                                   `%%(diary-sabbath-candles)'
  125.                                         Make a Friday diary entry that
  126.                                         tells the *local time* of
  127.                                         Sabbath candle lighting.
  128.                                   `%%(diary-omer)'
  129.                                         Make a diary entry that gives
  130.                                         the omer count, when
  131.                                         appropriate.
  132.                                   `%%(diary-yahrzeit MONTH DAY YEAR) NAME'
  133.                                         Make a diary entry marking the
  134.                                         anniversary of a date of death.
  135.                                         The date is the *Gregorian*
  136.                                         (civil) date of death.  The
  137.                                         diary entry appears on the
  138.                                         proper Hebrew calendar
  139.                                         anniversary and on the day
  140.                                         before.  (In the European
  141.                                         style, the order of the
  142.                                         parameters is changed to DAY,
  143.                                         MONTH, YEAR.)
  144. File: elisp,  Node: Appt Customizing,  Prev: Sexp Diary Entries,  Up: Calendar
  145. Customizing Appointment Reminders
  146. =================================
  147.                                       You can specify exactly how Emacs
  148. reminds you of an appointment and how far in advance it begins doing
  149. so.  Here are the variables that you can set:
  150.                                   `appt-message-warning-time'
  151.                                         The time in minutes before an
  152.                                         appointment that the reminder
  153.                                         begins.  The default is 10
  154.                                         minutes.
  155.                                   `appt-audible'
  156.                                         If this is `t' (the default),
  157.                                         Emacs rings the terminal bell
  158.                                         for appointment reminders.
  159.                                   `appt-visible'
  160.                                         If this is `t' (the default),
  161.                                         Emacs displays the appointment
  162.                                         message in echo area.
  163.                                   `appt-display-mode-line'
  164.                                         If this is `t' (the default),
  165.                                         Emacs displays the number of
  166.                                         minutes to the appointment on
  167.                                         the mode line.
  168.                                   `appt-msg-window'
  169.                                         If this is `t' (the default),
  170.                                         Emacs displays the appointment
  171.                                         message in another window.
  172.                                   `appt-display-duration'
  173.                                         The number of seconds an
  174.                                         appointment message is
  175.                                         displayed.  The default is 5
  176.                                         seconds.
  177. File: elisp,  Node: Tips,  Next: GNU Emacs Internals,  Prev: Calendar,  Up: Top
  178. Tips and Standards
  179. ******************
  180.                                       This chapter describes no
  181. additional features of Emacs Lisp.  Instead it gives advice on making
  182. effective use of the features described in the previous chapters.
  183.                                    * Menu:
  184.                                    
  185.                                    * Style Tips::                Writing clean and robust programs.
  186.                                    * Compilation Tips::          Making compiled code run fast.
  187.                                    * Documentation Tips::        Writing readable documentation strings.
  188.                                    * Comment Tips::          Conventions for writing comments.
  189.                                    * Library headers::           Standard headers for library packages.
  190. File: elisp,  Node: Style Tips,  Next: Compilation Tips,  Prev: Tips,  Up: Tips
  191. Writing Clean Lisp Programs
  192. ===========================
  193.                                       Here are some tips for avoiding
  194. common errors in writing Lisp code intended for widespread use:
  195.                                       * Since all global variables
  196.                                         share the same name space, and
  197.                                         all functions share another
  198.                                         name space, you should choose a
  199.                                         short word to distinguish your
  200.                                         program from other Lisp
  201.                                         programs.  Then take care to
  202.                                         begin the names of all global
  203.                                         variables, constants, and
  204.                                         functions with the chosen
  205.                                         prefix.  This helps avoid name
  206.                                         conflicts.
  207.                                         This recommendation applies
  208.                                         even to names for traditional
  209.                                         Lisp primitives that are not
  210.                                         primitives in Emacs Lisp--even
  211.                                         to `cadr'.  Believe it or not,
  212.                                         there is more than one
  213.                                         plausible way to define `cadr'.
  214.                                         Play it safe; append your name
  215.                                         prefix to produce a name like
  216.                                         `foo-cadr' or `mylib-cadr'
  217.                                         instead.
  218.                                         If one prefix is insufficient,
  219.                                         your package may use two or
  220.                                         three alternative common
  221.                                         prefixes, so long as they make
  222.                                         sense.
  223.                                         Separate the prefix from the
  224.                                         rest of the symbol name with a
  225.                                         hyphen, `-'.  This will be
  226.                                         consistent with Emacs itself
  227.                                         and with most Emacs Lisp
  228.                                         programs.
  229.                                       * It is often useful to put a
  230.                                         call to `provide' in each
  231.                                         separate library program, at
  232.                                         least if there is more than one
  233.                                         entry point to the program.
  234.                                       * If one file FOO uses a macro
  235.                                         defined in another file BAR,
  236.                                         FOO should contain `(require
  237.                                         'BAR)' before the first use of
  238.                                         the macro.  (And BAR should
  239.                                         contain `(provide 'BAR)', to
  240.                                         make the `require' work.)  This
  241.                                         will cause BAR to be loaded
  242.                                         when you byte-compile FOO.
  243.                                         Otherwise, you risk compiling
  244.                                         FOO without the necessary macro
  245.                                         loaded, and that would produce
  246.                                         compiled code that won't work
  247.                                         right.  *Note Compiling
  248.                                         Macros::.
  249.                                       * If you define a major mode,
  250.                                         make sure to run a hook
  251.                                         variable using `run-hooks',
  252.                                         just as the existing major
  253.                                         modes do.  *Note Hooks::.
  254.                                       * Please do not define `C-c
  255.                                         LETTER' as a key in your major
  256.                                         modes.  These sequences are
  257.                                         reserved for users; they are the
  258.                                         *only* sequences reserved for
  259.                                         users, so we cannot do without
  260.                                         them.
  261.                                         Instead, define sequences
  262.                                         consisting of `C-c' followed by
  263.                                         a non-letter.  These sequences
  264.                                         are reserved for major modes.
  265.                                         Changing all the major modes in
  266.                                         Emacs 18 so they would follow
  267.                                         this convention was a lot of
  268.                                         work.  Abandoning this
  269.                                         convention would waste that
  270.                                         work and inconvenience the
  271.                                         users.
  272.                                       * It is a bad idea to define
  273.                                         aliases for the Emacs
  274.                                         primitives.  Use the standard
  275.                                         names instead.
  276.                                       * Redefining an Emacs primitive
  277.                                         is an even worse idea.  It may
  278.                                         do the right thing for a
  279.                                         particular program, but there
  280.                                         is no telling what other
  281.                                         programs might break as a
  282.                                         result.
  283.                                       * If a file does replace any of
  284.                                         the functions or library
  285.                                         programs of standard Emacs,
  286.                                         prominent comments at the
  287.                                         beginning of the file should
  288.                                         say which functions are
  289.                                         replaced, and how the behavior
  290.                                         of the replacements differs
  291.                                         from that of the originals.
  292.                                       * If a file requires certain
  293.                                         standard library programs to be
  294.                                         loaded beforehand, then the
  295.                                         comments at the beginning of
  296.                                         the file should say so.
  297.                                       * Please keep the names of your
  298.                                         Emacs Lisp source files to 13
  299.                                         characters or less.  This way,
  300.                                         if the files are compiled, the
  301.                                         compiled files' names will be
  302.                                         14 characters or less, which is
  303.                                         short enough to fit on all kinds
  304.                                         of Unix systems.
  305.                                       * Don't use `next-line' or
  306.                                         `previous-line' in programs;
  307.                                         nearly always, `forward-line'
  308.                                         is more convenient as well as
  309.                                         more predictable and robust.
  310.                                         *Note Text Lines::.
  311.                                       * Don't use functions that set
  312.                                         the mark in your Lisp code
  313.                                         (unless you are writing a
  314.                                         command to set the mark).  The
  315.                                         mark is a user-level feature,
  316.                                         so it is incorrect to change
  317.                                         the mark except to supply a
  318.                                         value for the user's benefit.
  319.                                         *Note The Mark::.
  320.                                         In particular, don't use these
  321.                                         functions:
  322.                                            * `beginning-of-buffer',
  323.                                              `end-of-buffer'
  324.                                            * `replace-string',
  325.                                              `replace-regexp'
  326.                                         If you just want to move point,
  327.                                         or replace a certain string,
  328.                                         without any of the other
  329.                                         features intended for
  330.                                         interactive users, you can
  331.                                         replace these functions with
  332.                                         one or two lines of simple Lisp
  333.                                         code.
  334.                                       * The recommended way to print a
  335.                                         message in the echo area is with
  336.                                         the `message' function, not
  337.                                         `princ'.  *Note The Echo Area::.
  338.                                       * When you encounter an error
  339.                                         condition, call the function
  340.                                         `error' (or `signal').  The
  341.                                         function `error' does not
  342.                                         return.  *Note Signaling
  343.                                         Errors::.
  344.                                         Do not use `message', `throw',
  345.                                         `sleep-for', or `beep' to
  346.                                         report errors.
  347.                                       * Avoid using recursive edits.
  348.                                         Instead, do what the Rmail `w'
  349.                                         command does: use a new local
  350.                                         keymap that contains one
  351.                                         command defined to switch back
  352.                                         to the old local keymap.  Or do
  353.                                         what the `edit-options' command
  354.                                         does: switch to another buffer
  355.                                         and let the user switch back at
  356.                                         will.  *Note Recursive
  357.                                         Editing::.
  358.                                       * In some other systems there is
  359.                                         a convention of choosing
  360.                                         variable names that begin and
  361.                                         end with `*'.  We don't use
  362.                                         that convention in Emacs Lisp,
  363.                                         so please don't use it in your
  364.                                         library.  (In fact, in Emacs
  365.                                         names of this form are
  366.                                         conventionally used for
  367.                                         program-generated buffers.) The
  368.                                         users will find Emacs more
  369.                                         coherent if all libraries use
  370.                                         the same conventions.
  371.                                       * Indent each function with
  372.                                         `C-M-q' (`indent-sexp') using
  373.                                         the default indentation
  374.                                         parameters.
  375.                                       * Don't make a habit of putting
  376.                                         close-parentheses on lines by
  377.                                         themselves; Lisp programmers
  378.                                         find this disconcerting.  Once
  379.                                         in a while, when there is a
  380.                                         sequence of many consecutive
  381.                                         close-parentheses, it may make
  382.                                         sense to split them in one or
  383.                                         two significant places.
  384.                                       * Please put a copyright notice
  385.                                         on the file if you give copies
  386.                                         to anyone.  Use the same lines
  387.                                         that appear at the top of the
  388.                                         Lisp files in Emacs itself.  If
  389.                                         you have not signed papers to
  390.                                         assign the copyright to the
  391.                                         Foundation, then place your
  392.                                         name in the copyright notice in
  393.                                         place of the Foundation's name.
  394. File: elisp,  Node: Compilation Tips,  Next: Documentation Tips,  Prev: Style Tips,  Up: Tips
  395. Tips for Making Compiled Code Fast
  396. ==================================
  397.                                       Here are ways of improving the
  398. execution speed of byte-compiled lisp programs.
  399.                                       * Use the `profile' library to
  400.                                         profile your program.  See the
  401.                                         file `profile.el' for
  402.                                         instructions.
  403.                                       * Use iteration rather than
  404.                                         recursion whenever possible.
  405.                                         Function calls are slow in
  406.                                         Emacs Lisp even when a compiled
  407.                                         function is calling another
  408.                                         compiled function.
  409.                                       * Using the primitive
  410.                                         list-searching functions
  411.                                         `memq', `assq' or `assoc' is
  412.                                         even faster than explicit
  413.                                         iteration.  It may be worth
  414.                                         rearranging a data structure so
  415.                                         that one of these primitive
  416.                                         search functions can be used.
  417.                                       * Certain built-in functions are
  418.                                         handled specially by the byte
  419.                                         compiler avoiding the need for
  420.                                         an ordinary function call.  It
  421.                                         is a good idea to use these
  422.                                         functions rather than
  423.                                         alternatives.  To see whether a
  424.                                         function is handled specially
  425.                                         by the compiler, examine its
  426.                                         `byte-compile' property.  If
  427.                                         the property is non-`nil', then
  428.                                         the function is handled
  429.                                         specially.
  430.                                         For example, the following
  431.                                         input will show you that `aref'
  432.                                         is compiled specially (*note
  433.                                         Array Functions::.) while `elt'
  434.                                         is not (*note Sequence
  435.                                         Functions::.):
  436.                                              (get 'aref 'byte-compile)
  437.                                                   => byte-compile-two-args
  438.                                              (get 'elt 'byte-compile)
  439.                                                   => nil
  440.                                       * Make small functions inline, so
  441.                                         that calls to them in compiled
  442.                                         code run faster.  *Note Inline
  443.                                         Functions::.
  444. File: elisp,  Node: Documentation Tips,  Next: Comment Tips,  Prev: Compilation Tips,  Up: Tips
  445. Tips for Documentation Strings
  446. ==============================
  447.                                       Here are some tips for the
  448. writing of documentation strings.
  449.                                       * Every command, function or
  450.                                         variable intended for users to
  451.                                         know about should have a
  452.                                         documentation string.
  453.                                       * An internal subroutine of a
  454.                                         Lisp program need not have a
  455.                                         documentation string, and you
  456.                                         can save space by using a
  457.                                         comment instead.
  458.                                       * The first line of the
  459.                                         documentation string should
  460.                                         consist of one or two complete
  461.                                         sentences which stand on their
  462.                                         own as a summary.  In
  463.                                         particular, start the line with
  464.                                         a capital letter and end with a
  465.                                         period.
  466.                                         The documentation string can
  467.                                         have additional lines which
  468.                                         expand on the details of how to
  469.                                         use the function or variable.
  470.                                         The additional lines should be
  471.                                         made up of complete sentences
  472.                                         also, but they may be filled if
  473.                                         that looks good.
  474.                                       * Do not start or end a
  475.                                         documentation string with
  476.                                         whitespace.
  477.                                       * Format the documentation string
  478.                                         so that it fits in an Emacs
  479.                                         window on an 80 column screen.
  480.                                         It is a good idea for most
  481.                                         lines to be no wider than 60
  482.                                         characters.  The first line can
  483.                                         be wider if necessary to fit the
  484.                                         information that ought to be
  485.                                         there.
  486.                                         However, rather than simply
  487.                                         filling the entire
  488.                                         documentation string, you can
  489.                                         make it much more readable by
  490.                                         choosing line breaks with care.
  491.                                         Use blank lines between topics
  492.                                         if the documentation string is
  493.                                         long.
  494.                                       * *Do not* indent subsequent
  495.                                         lines of a documentation string
  496.                                         so that the text is lined up in
  497.                                         the source code with the text
  498.                                         of the first line.  This looks
  499.                                         nice in the source code, but
  500.                                         looks bizarre when users view
  501.                                         the documentation.  Remember
  502.                                         that the indentation before the
  503.                                         starting double-quote is not
  504.                                         part of the string!
  505.                                       * A variable's documentation
  506.                                         string should start with `*' if
  507.                                         the variable is one that users
  508.                                         would want to set interactively
  509.                                         often.  If the value is a long
  510.                                         list, or a function, or if the
  511.                                         variable would only be set in
  512.                                         init files, then don't start
  513.                                         the documentation string with
  514.                                         `*'.  *Note Defining
  515.                                         Variables::.
  516.                                       * The documentation string for a
  517.                                         variable that is a yes-or-no
  518.                                         flag should start with words
  519.                                         such as "Non-nil means...", to
  520.                                         make it clear both that the
  521.                                         variable only has two
  522.                                         meaningfully distinct values
  523.                                         and which value means "yes".
  524.                                       * When a function's documentation
  525.                                         string mentions the value of an
  526.                                         argument of the function, use
  527.                                         the argument name in capital
  528.                                         letters as if it were a name
  529.                                         for that value.  Thus, the
  530.                                         documentation string of the
  531.                                         function `/' refers to its
  532.                                         second argument as `DIVISOR'.
  533.                                         Also use all caps for
  534.                                         meta-syntactic variables, such
  535.                                         as when you show the
  536.                                         decomposition of a list or
  537.                                         vector into subunits, some of
  538.                                         which may be variable.
  539.                                       * When a documentation string
  540.                                         refers to a Lisp symbol, write
  541.                                         it as it would be printed
  542.                                         (which usually means in lower
  543.                                         case), with single-quotes
  544.                                         around it.  For example:
  545.                                         ``lambda''.  There are two
  546.                                         exceptions: write `t' and `nil'
  547.                                         without single-quotes.
  548.                                       * Don't write key sequences
  549.                                         directly in documentation
  550.                                         strings.  Instead, use the
  551.                                         `\\[...]' construct to stand
  552.                                         for them.  For example, instead
  553.                                         of writing `C-f', write
  554.                                         `\\[forward-char]'.  When the
  555.                                         documentation string is
  556.                                         printed, Emacs will substitute
  557.                                         whatever key is currently bound
  558.                                         to `forward-char'.  This will
  559.                                         usually be `C-f', but if the
  560.                                         user has moved key bindings, it
  561.                                         will be the correct key for
  562.                                         that user.  *Note Keys in
  563.                                         Documentation::.
  564.                                       * In documentation strings for a
  565.                                         major mode, you will want to
  566.                                         refer to the key bindings of
  567.                                         that mode's local map, rather
  568.                                         than global ones.  Therefore,
  569.                                         use the construct `\\<...>'
  570.                                         once in the documentation
  571.                                         string to specify which key map
  572.                                         to use.  Do this before the
  573.                                         first use of `\\[...]'.  The
  574.                                         text inside the `\\<...>'
  575.                                         should be the name of the
  576.                                         variable containing the local
  577.                                         keymap for the major mode.
  578.                                         It is not practical to use
  579.                                         `\\[...]' very many times,
  580.                                         because display of the
  581.                                         documentation string will
  582.                                         become slow.  So use this to
  583.                                         describe the most important
  584.                                         commands in your major mode,
  585.                                         and then use `\\{...}' to
  586.                                         display the rest of the mode's
  587.                                         keymap.
  588.                                       * Don't use the term "Elisp",
  589.                                         since that is or was a
  590.                                         trademark.  Use the term "Emacs
  591.                                         Lisp".
  592. File: elisp,  Node: Comment Tips,  Next: Library Headers,  Prev: Documentation Tips,  Up: Tips
  593. Tips on Writing Comments
  594. ========================
  595.                                       We recommend these conventions
  596. for where to put comments and how to indent them:
  597.                                   `;'
  598.                                         Comments that start with a
  599.                                         single semicolon, `;', should
  600.                                         all be aligned to the same
  601.                                         column on the right of the
  602.                                         source code.  Such comments
  603.                                         usually explain how the code on
  604.                                         the same line does its job.  In
  605.                                         Lisp mode and related modes,
  606.                                         the `M-;' (`indent-for-comment')
  607.                                         command automatically inserts
  608.                                         such a `;' in the right place,
  609.                                         or aligns such a comment if it
  610.                                         is already inserted.
  611.                                         (The following examples are
  612.                                         taken from the Emacs sources.)
  613.                                              (setq base-version-list                 ; there was a base
  614.                                                    (assoc (substring fn 0 start-vn)  ; version to which
  615.                                                           file-version-assoc-list))  ; this looks like
  616.                                                                                      ; a subversion
  617.                                   `;;'
  618.                                         Comments that start with two
  619.                                         semicolons, `;;', should be
  620.                                         aligned to the same level of
  621.                                         indentation as the code.  Such
  622.                                         comments are used to describe
  623.                                         the purpose of the following
  624.                                         lines or the state of the
  625.                                         program at that point.  For
  626.                                         example:
  627.                                              (prog1 (setq auto-fill-function
  628.                                                           ...
  629.                                                           ...
  630.                                                ;; update mode-line
  631.                                                (force-mode-line-update)))
  632.                                         These comments are also written
  633.                                         before a function definition to
  634.                                         explain what the function does
  635.                                         and how to call it properly.
  636.                                   `;;;'
  637.                                         Comments that start with three
  638.                                         semicolons, `;;;', should start
  639.                                         at the left margin.  Such
  640.                                         comments are not used within
  641.                                         function definitions, but are
  642.                                         used to make more general
  643.                                         comments.  For example:
  644.                                              ;;; This Lisp code is run in Emacs
  645.                                              ;;; when it is to operate asa server
  646.                                              ;;; for other processes.
  647.                                   `;;;;'
  648.                                         Comments that start with four
  649.                                         semicolons, `;;;;', should be
  650.                                         aligned to the left margin and
  651.                                         are used for headings of major
  652.                                         sections of a program.  For
  653.                                         example:
  654.                                              ;;;; The kill ring
  655.                                    The indentation commands of the Lisp
  656. modes in Emacs, such as `M-;' (`indent-for-comment') and TAB
  657. (`lisp-indent-line') automatically indent comments according to these
  658. conventions, depending on the the number of semicolons.  *Note
  659. Manipulating Comments: (emacs)Comments.
  660.                                       If you wish to "comment out" a
  661. number of lines of code, use triple semicolons at the beginnings of the
  662. lines.
  663.                                       Any character may be included in
  664. a comment, but it is advisable to precede a character with syntactic
  665. significance in Lisp (such as `\' or unpaired `(' or `)') with a `\',
  666. to prevent it from confusing the Emacs commands for editing Lisp.
  667. File: elisp,  Node: Library Headers,  Prev: Comment Tips,  Up: Tips
  668. Conventional Headers for Emacs Library Packages
  669. ===============================================
  670.                                       There are some standard
  671. identication headers used in Emacs 19 library packages to assist the
  672. help system, track authors and versions for maintainence purposes, and
  673. enable the generation of various kinds of databases and documentation.
  674.                                       This section explains them and
  675. why you should try to use the same conventions in your packages,
  676. especially if you want to submit them to FSF.
  677.                                       Here's the head of a file written
  678. using the library conventions:
  679.                                         ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
  680.                                         
  681.                                         ;; Copyright (C) 1992 Free Software Foundation, Inc.
  682.                                         
  683.                                         ;; Author: Eric S. Raymond <esr
  684.                                         ;; Maintainer: Eric S. Raymond <esr
  685.                                         ;; Created: 14 Jul 1992
  686.                                         ;; Version: 1.2
  687.                                         ;; Keywords: docs
  688.                                         ;; Bogus-Bureaucratic-Cruft: Gruad will get you if you don't watch out!
  689.                                         
  690.                                         ;; This file is part of GNU Emacs.
  691.                                       Here are the new features:
  692.                                       *Header line* -- makes it
  693. possible to extract a one-line summary of the package's uses
  694. automatically for use in library synopses, KWIC indexes and the like.
  695.                                       Format is three semicolons,
  696. followed by the filename, followed by three dashes, followed by the
  697. summary.  All fields space-separated.
  698.                                       *Author line* -- contains the
  699. name and net address of at least the principal author.
  700.                                       If there are multiple authors,
  701. they should be listed on continuation lines led by `;;<TAB>', like this:
  702.                                         ;; Author: Ashwin Ram <Ram-Ashwin
  703.                                         ;;    Dave Sill <de5
  704.                                         ;;    David Lawrence <tale
  705.                                         ;;    Noah Friedman <friedman
  706.                                         ;;    Joe Wells <jbw
  707.                                         ;;    Dave Brennan <brennan
  708.                                         ;;    Eric Raymond <esr
  709.                                       This field may have some special
  710. values; notably "FSF", meaning "Free Software Foundation".
  711.                                       *Maintainer line* -- should be a
  712. single name/address as in the Author line, or an address only, or the
  713. string "FSF".  If there is no maintainer line, the person(s) in the
  714. Author field are presumed to be it.  The example in this file is mildly
  715. bogus because the maintainer line is redundant.
  716.                                       The idea behind these two fields
  717. is to be able to write a lisp function that does "send mail to the
  718. author" without having to mine the name out by hand. Please be careful
  719. about surrounding the network address with <> if there's also a name in
  720. the field.
  721.                                       *Created line* -- optional, gives
  722. the original creation date of the file.  For historical interest,
  723. basically.
  724.                                       *Version line* -- intended to
  725. give the reader a clue if they're looking at a different version of the
  726. file than the one they're accustomed to.  Not needed if you have an RCS
  727. or SCCS header.
  728.                                       *Adapted-By line* -- this is for
  729. FSF's internal use.  The person named in this field was the one
  730. responsible for installing and adapting the package for the
  731. distribution.  (This file doesn't have one because the author *is* one
  732. of the maintainers.)
  733.                                       *Keywords line* -- used by the
  734. package-finder code for finding elisp code related to a topic.  This
  735. field is important; it's how people will find your package when they're
  736. looking forthings by topic area.
  737.                                       *Bogus-Bureaucratic-Cruft line*
  738. -- this is a joke.  We figured we should satirize this design before
  739. someone else did.  Also, it illustrates the possibility that other
  740. headers may be added in the future for new purposes.
  741.                                       There are a few other stylized
  742. comments all the distribution files comtain.  These are:
  743.                                       *Commentary line* -- optional,
  744. enables lisp code to find the developer's and maintainers' explanations
  745. of the package internals.  It looks like this:
  746.                                       smallexample ;;; Commentary:
  747. smallexample
  748.                                       and should be located after the
  749. GNU copyright but before the package's header comments (if any).
  750.                                       *Change log line* -- optional,
  751. exists to terminate the commentary section and start a change-log part,
  752. if one exists.  It looks like this:
  753.                                       smallexample ;;; Change Log:
  754. smallexample
  755.                                       *Code line* -- exists so lisp can
  756. know where the commentary and/or change-log sections end.  It looks
  757. like this:
  758.                                       smallexample ;;; Code:
  759. smallexample
  760.                                       *Footer line* -- marks
  761. end-of-file so it can be distinguished from an expanded formfeed or the
  762. results of truncation.  This must be the *last* line in the file.
  763. Example:
  764.                                       smallexample ;;; lisp-mnt.el ends
  765. here  smallexample
  766.                                       The mode used as an example
  767. actually exists and can actually be used to generate these headers
  768. semi-automatically.  It provides functions which lisp programs can use
  769. to etract various useful pieces of information from these headers.
  770.